{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Part 8 bis - Introduction to Protocols\n",
    "\n",
    "### Context \n",
    "\n",
    "Now that we've been through Plans, we'll introduce a new object called the Protocol. A Protocol coordinates a sequence of Plans, deploys them on distant workers\n",
    "and run them in a single pass.\n",
    "\n",
    "It's a high level object which contains the logic of a complex computation\n",
    "distributed across several workers. The main feature of Protocol is the\n",
    "ability to be sent / searched / fetched back between workers, and finally\n",
    "deployed to identified workers. So a user can design a protocol, upload it\n",
    "to a cloud worker, and any other workers will be able to search for it,\n",
    "download it, and apply the computation program it contains on the workers\n",
    "that it is connected to.\n",
    "\n",
    "Let's see how to use it!\n",
    "\n",
    "Authors:\n",
    "- Théo Ryffel - Twitter [@theoryffel](https://twitter.com/theoryffel) - GitHub: [@LaRiffle](https://github.com/LaRiffle)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Create and deploy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Protocol are created by providing a list of pairs `(worker, plan)`. `worker` can be either a real\n",
    "worker or a worker id or a string to represent a fictive worker. This\n",
    "last case can be used at creation to specify that two plans should be\n",
    "owned (or not owned) by the same worker at deployment. `plan` can\n",
    "either be a Plan or a PointerPlan."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import torch as th\n",
    "import syft as sy\n",
    "hook = sy.TorchHook(th)\n",
    "\n",
    "# IMPORTANT: Local worker should not be a client worker\n",
    "hook.local_worker.is_client_worker = False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's define 3 plans and feed them to a protocol. They all perform an increment operation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@sy.func2plan(args_shape=[(1,)])\n",
    "def inc1(x):\n",
    "    return x + 1\n",
    "\n",
    "@sy.func2plan(args_shape=[(1,)])\n",
    "def inc2(x):\n",
    "    return x + 1\n",
    "\n",
    "@sy.func2plan(args_shape=[(1,)])\n",
    "def inc3(x):\n",
    "    return x + 1\n",
    "\n",
    "protocol = sy.Protocol([(\"worker1\", inc1), (\"worker2\", inc2), (\"worker3\", inc3)])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we need to bind the Protocol to workers, which is done by calling `.deploy(*workers)`. Let's create some workers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "bob = sy.VirtualWorker(hook, id=\"bob\")\n",
    "alice = sy.VirtualWorker(hook, id=\"alice\")\n",
    "charlie = sy.VirtualWorker(hook, id=\"charlie\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "workers = alice, bob, charlie\n",
    "\n",
    "protocol.deploy(*workers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see that the plans have already been sent to the appropriate workers: it has been deployed!\n",
    "\n",
    "This has been done in 2 phases: first, we map the fictive workers provided at creation\n",
    "(named by strings) to the provided workers, and second, we send the corresponding\n",
    "plans to each of them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Run a protocol\n",
    "\n",
    "Running a protocol means executing all the plans sequentially. To do so, you provide some input data which is sent to the first plan location. This first plan is\n",
    "run and its output is moved to the second plan location, and so on. The final\n",
    "result is returned after all plans have run, and it is composed of pointers to\n",
    "the last plan location."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = th.tensor([1.0])\n",
    "ptr = protocol.run(x)\n",
    "ptr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ptr.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The input 1.0 has been through the 3 plans and so has been incremented 3 times, that's why it now equals 4.0!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Actually, you can also **run a protocol remotely** on some pointers to data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "james = sy.VirtualWorker(hook, id=\"james\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol.send(james)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = th.tensor([1.0]).send(james)\n",
    "ptr = protocol.run(x)\n",
    "ptr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you see the result is a pointer to james"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ptr = ptr.get()\n",
    "ptr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ptr = ptr.get()\n",
    "ptr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Search for a protocol\n",
    "\n",
    "In real settings you might want to download a remote protocol, to deploy it on your workers and to run it with you data:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's initialize a protocol **which is not deployed**, and put it on a remote worker"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol = sy.Protocol([(\"worker1\", inc1), (\"worker2\", inc2), (\"worker3\", inc3)])\n",
    "protocol.tag('my_protocol')\n",
    "protocol.send(james)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "me = sy.hook.local_worker # get access to me as a local worker"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we launch a search to find the protocol"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "responses = me.request_search(['my_protocol'], location=james)\n",
    "responses"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You have access to a pointer to a Protocol"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ptr_protocol = responses[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like usual pointer you can get it back:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol_back = ptr_protocol.get()\n",
    "protocol_back"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And we can do like we did in parts 1. & 2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol_back.deploy(alice, bob, charlie)\n",
    "\n",
    "x = th.tensor([1.0])\n",
    "ptr = protocol_back.run(x)\n",
    "ptr.get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More real world examples will come with Protocols, but you can already see all the possibilities opened by this new object!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Star PySyft on GitHub\n",
    "\n",
    "The easiest way to help our community is just by starring the repositories! This helps raise awareness of the cool tools we're building.\n",
    "\n",
    "- [Star PySyft](https://github.com/OpenMined/PySyft)\n",
    "\n",
    "### Pick our tutorials on GitHub!\n",
    "\n",
    "We made really nice tutorials to get a better understanding of what Federated and Privacy-Preserving Learning should look like and how we are building the bricks for this to happen.\n",
    "\n",
    "- [Checkout the PySyft tutorials](https://github.com/OpenMined/PySyft/tree/master/examples/tutorials)\n",
    "\n",
    "\n",
    "### Join our Slack!\n",
    "\n",
    "The best way to keep up to date on the latest advancements is to join our community! \n",
    "\n",
    "- [Join slack.openmined.org](http://slack.openmined.org)\n",
    "\n",
    "### Join a Code Project!\n",
    "\n",
    "The best way to contribute to our community is to become a code contributor! If you want to start \"one off\" mini-projects, you can go to PySyft GitHub Issues page and search for issues marked `Good First Issue`.\n",
    "\n",
    "- [Good First Issue Tickets](https://github.com/OpenMined/PySyft/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n",
    "\n",
    "### Donate\n",
    "\n",
    "If you don't have time to contribute to our codebase, but would still like to lend support, you can also become a Backer on our Open Collective. All donations go toward our web hosting and other community expenses such as hackathons and meetups!\n",
    "\n",
    "- [Donate through OpenMined's Open Collective Page](https://opencollective.com/openmined)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
